My concern with these is that the extra options available to the run module cannot easily be added.

While eg. themes could be debugged by changing the config file, some options are only available on the command-line, such as 'explore mode' right now.

What about making Makefile to pass things to debug-profile & debug commands? Maybe it would be useful to use ARGS to forward arguments to the ´´run´´ module. What do you think about something like:

debug-profile: venv
	@echo "= Profiling enabled ="
	$(PYTHON) -m zulipterminal.cli.run --profile $(ARGS)

Overall, I'm not yet convinced that wrapping what is already in zulip-term into a make target is helpful.

Passing ARGS to make is some way around my original concern, but if I wanted debugging and profiling, which one of these would I do (or prefer - or document?):

• make debug --profile ?
• make debug-profile -d ?
• make && zulip-term -d --profile (or with make venv) ?

The only difference for the latter is the title line establishing profiling is enabled - debugging is mentioned at startup if enabled. A small fix to the main code could make that clearer.

So while I originally said the extra parameters were the issue, it really comes down to whether eg. make debug is cleaner than simply zulip-term -d (or zulip-term --debug). The extra part is running make each time, which does ensure the environment is up to date, but isn't necessarily required frequently.

Simplifying this, ultimately we could end up with a "run" target, which is what tools like pipenv and uv can enable, but we have zulip-term set up for this already.

This certainly cleans files from the current folder, but not necessarily from where the files are accumulating.

Here I've only seen profile files in /tmp/, and with a random name; have you seen it in the local directory? Do you also see the zulip-terminal.prof name?

I'm also a little wary of making it too easy to delete the other files, since while that information can accumulate and it's not clear which is worth keeping, it can also often be really useful! I suspect a more refined solution could be to build upon the move to use .config and store debugging and tracebacks in different folders by name/date/branch/etc.

Yeah, you're totally right. I had a messy gh codespace that I was organizing everything at that moment, so I may had a mistake about temp files. Cleaning files, especially the logs right now make me concern about changes more right now too. Yes, logs are long and hard to read files but deleting could make feel losing daily to-do. What about action of keeping an option for normal - developer mode so normal users just delete logs & devs keep them

I believe there are XDG or similar directories for logs and so on, which are similar to the .config standard; there's an open PR I need to check for migrating to using .config. If so, a centralized location might be useful, grouped somehow by the organization and date/time of the session.

To clarify, I was referring to the last sentence of my first comment in this thread. When we have separate sets of files for each session by date/organization, it would keep generated files organized and out of the current directory, as well as make it easier to clean them up in some defined way :)

How does this compare to the section above?

I created because remote debugging example just takes the pudb tip and puts it into action with a real use case, like debugging send_message. It's not just explaining the tool, but showing exactly how to use it in a scenario that devs can actually relate to. That makes it way easier to follow for anyone who's never set this up before, and helps connect the dots between the theory and how it works in practice too

There isn't really a big difference in content between your example and the earlier section, and in the interest of avoiding duplication I'd rather that we improve the existing section with more specific text instead?

• I like the numbered list (if we end up having enough steps - specifically re debug mode!)
• It's unclear to me that we need to pick a specific existing file or function, since names might change, but including it in a function/location looks better
• I do like the extra comments in your version
• It may be worth having the breakpoint further down, to indicate it need not be at the top
• I know it's in the original documentation, but do we need debug mode for pudb? I suspect these are independent settings, unless one is using print also?
• The section title can likely be improved by combining the existing and your draft; pudb and telnet are less important in the title

From testing just now:

• the telnet details output to the main terminal if I breakpoint before the TUI
• adding a breakpoint elsewhere can cause the app to seemingly lock up?
• debug mode doesn't appear to affect this ^

Have you tried remote debugging?

It would be useful to have a link to the pudb remote debugging docs - and that may help with understanding how to handle remote debugging more generally, and give a few extra tips on using it effectively for devs.

Please break this change out into a separate commit, or one for base improvements and then another for possible improvements that need more discussion - we can always squash commits together later, or merge one first and continue discussing the other.

This makes it available to users who install the basic package, not just run it from the source tree; is that the intention?

Yeah, that was the idea. Making the debug_helper available to users who install the basic package means they can use the debugging tools whether they’re running from the source tree or from an installed environment. If this brings up any concerns, I’m down to discuss it

I think this would be helpful because more input about problems helps us solve them more effectively

If this is installed for all users, not just devs, then we don't need to update helper_deps with requests; it will already be installed for the main app, indirectly via zulip as it stands, though we could potentially add requests as a direct dependency.

There's no problem with having small extra tools to help users debug issues, though 'debug' is a very broad name, and splitting the tool(s) out may be good.

This seems to simply wrap commands, as per:

• zulip-term-debug run vs zulip-term -d
• zulip-term-debug run --profile vs zulip-term -d --profile

What is the benefit of this?

Since 2 weeks passed, I think I was trying to clean things up or reframe it, but I didn't add any new functionality. I can roll that back and just stick to the original commands if you want

This appears to be similar to the Makefile changes I commented on elsewhere, so I'd skip it.

This looks like something that could belong in render_symbols.py, or perhaps an extension of it?

That existing tool checks the symbols that are currently being used, rather than an assortment of sample ones.

You're right, this is similar to what render_symbols.py does, but there's a difference. This script tests a range of symbols for general Unicode rendering in the terminal, while render_symbols.py focuses on the symbols used specifically in Zulip Terminal.

If the goal is to extend render_symbols.py for broader Unicode testing, this code could be added as a feature. Otherwise, it could stay separate as part of a general terminal debugging tool. What do you think—integrate it or keep it separate?

We have the separate script since it provides an easy way to visually check how the symbols that we actively use are being output.

You've described the difference, but what is the benefit of testing the symbols you listed, compared to those in render_symbols.py?

I could see outputting the terminal environment (TERM, etc.) as being useful for debugging, and potentially outside of a TUI environment, in case the TUI fails for some reason (including due to those parameters?). However, we could output it before zulip-term enters the GUI. If we're in the TUI, then those could go in the about box, or something like it, as could render_symbols I guess, in a 'debug' sub-popup - in addition to the separate script we have now.

It is possible that some symbols aren't included there and would render badly on some terminals, so if you do find some then we can refactor those similarly to the others.

While the main zulip-term script does check for connectivity, and the server version can be listed from within it, I can see a simple tool along these lines being useful.

However, rather than having a script with semi-duplicate code from run.py, it would be useful to use existing functions from there - it looks very similar to it?

There is plenty of server information available other than the version, which could also be used to help with authentication issues, for example.

I think good approach would be to refactor the relevant logic in run.py into reusable utility functions or a module. These functions could then be imported into both run.py and the debugging script, by ensuring shared functionality

That would seem like a reasonable way forward 👍

This can find lots of issues (my files are quite large right now!), but could you give an example of how it has helped you? Do you have a specific motivation for this?

I would expect that reading through the file to get multiple lines of context would be more helpful?

If this is also for reporting errors to maintainers/developers, then context can be useful.

The reason I added this is to quickly spot common error patterns, which helps a lot with large files. But yeah, I get it — without context, it’s not super helpful. Like, finding an ERROR by itself doesn’t really tell us why it happened or what led up to it.

This would likely be simpler to apply when we have multiple log files (as mentioned in another comment) since it would likely make it easier to eg. deduplicate errors, or find patterns, between each session.

If this tool were to exist, it would be useful to identify multiple possible files. We have a tracebacks file, an API log, and a thread-exceptions log as it stands.

I wouldn't expect debug.log to necessarily have the error_patterns you mention, since anything can be 'print'ed into them, so having a default of debug.log with those patterns is surprising.

You're right. if the tool's for analyzing logs properly, it should handle multiple log files like tracebacks, API logs, and thread-exceptions. Limiting it to debug.log with hardcoded patterns makes it less useful.

A better approach:
Let users specify which log files to analyze.
Include default or custom patterns for each file.
Maybe add auto-detection to adjust patterns based on the log file.

To confirm, adding this is definitely an improvement - split this into a separate commit and with a few changes it's something to add independently of anything else in this PR.

Thoughts on the content:

• zulip-term indicates the location of the prof file and a way to run snakeviz, after it exits; mention that?
• As mentioned at debugging functionality added #1569 (comment), the name of the 'prof' file is unlikely to be specifically as in the quoted bash text?
• Possibly note that for running zulip-term, that you run it as you normally would, but with --profile added; I'd choose that type of wording since the current command line might suggest you run it just as it is, and if someone is using -c path/to/zuliprc then it will behave differently or fail

There isn't really a big difference in content between your example and the earlier section, and in the interest of avoiding duplication I'd rather that we improve the existing section with more specific text instead?

• I like the numbered list (if we end up having enough steps - specifically re debug mode!)
• It's unclear to me that we need to pick a specific existing file or function, since names might change, but including it in a function/location looks better
• I do like the extra comments in your version
• It may be worth having the breakpoint further down, to indicate it need not be at the top
• I know it's in the original documentation, but do we need debug mode for pudb? I suspect these are independent settings, unless one is using print also?
• The section title can likely be improved by combining the existing and your draft; pudb and telnet are less important in the title

From testing just now:

• the telnet details output to the main terminal if I breakpoint before the TUI
• adding a breakpoint elsewhere can cause the app to seemingly lock up?
• debug mode doesn't appear to affect this ^

Have you tried remote debugging?

It would be useful to have a link to the pudb remote debugging docs - and that may help with understanding how to handle remote debugging more generally, and give a few extra tips on using it effectively for devs.

Please break this change out into a separate commit, or one for base improvements and then another for possible improvements that need more discussion - we can always squash commits together later, or merge one first and continue discussing the other.

To clarify, I was referring to the last sentence of my first comment in this thread. When we have separate sets of files for each session by date/organization, it would keep generated files organized and out of the current directory, as well as make it easier to clean them up in some defined way :)

If this is installed for all users, not just devs, then we don't need to update helper_deps with requests; it will already be installed for the main app, indirectly via zulip as it stands, though we could potentially add requests as a direct dependency.

There's no problem with having small extra tools to help users debug issues, though 'debug' is a very broad name, and splitting the tool(s) out may be good.

This would likely be simpler to apply when we have multiple log files (as mentioned in another comment) since it would likely make it easier to eg. deduplicate errors, or find patterns, between each session.